PC Media 3

home *** CD-ROM | disk | FTP | other *** search

/ PC Media 3 / PC MEDIA CD03.iso / share / os2 / v2_614 / vc10 < prev next >

Wrap

Text File | 1993-12-16 | 13.9 KB | 276 lines

.TOPIC: Virtual Script Language (VScript) VBBS 6.12 Documentation -- 10-1 ╔════════════════════════════════════════════════════════════════╗ ║ CHAPTER TEN VIRTUAL SCRIPT LANGUAGE <VSCRIPT> ║ ╚════════════════════════════════════════════════════════════════╝ SCRIPT LANGUAGE INTRODUCTION ════════════════════════════ One of the features that makes VBBS unique is its script language compiler - VCOM.EXE. Along with the built-in command interpreter in VBBS, it allows you to make changes to your BBS quickly and easily. The scripts are nothing more than a series of commands listed in a plain ASCII text file, and you don't even need to be a programmer to write one. All you need to cre- ate scripts are a text editor or word processor that allows you to save in ASCII format (see your word processor documentation for more info) and a little patience. In no time, you will be writing up scripts and swapping them with other VBBS sysops like a pro. Scripts are generic to both the DOS and OS/2 versions. GENERAL RESTRICTIONS ════════════════════ The VBBS script language has only one major restriction; there can only be a total of 7 'tokens' on a line. A token is defined as either a single unspaced series of characters (for example, a command or a number) or any group of characters and spaces surrounded by single or double quotes (also called a "string".) The script language is NOT case-sensitive; any capitalization used in this text is not required and is done only for clarity. All the scripts that you create should be placed into your scripts directory as defined in VCONFIG - PATHS Configuration; see Chapter 2 for more information on setting your paths. The only other restrictions pertain to names. All of your script files MUST have the extension .V and all of your names for variables must begin with a '$', e.g., $variable. SCRIPT COMPILER (VCOM.EXE) ══════════════════════════ The program VCOM.EXE is the compiler that prepares your script file for use by VBBS's interpreter. It takes the script file that you have created and builds the two files that VBBS actually uses from it. These two files have the same name as the script file but have .LIT and .COD as their extensions. Compilation of a script is accomplished by changing to your scripts directory and executing the command line: VCOM <script name> VBBS 6.12 Documentation -- 10-2 You do not need to use the extension to compile the script. The compiler can detect some errors in the script file during the compilation. These errors are predominantly related to the commands that 'jump' around within a script. These commands are GO, TEST, TESTVAL, CALL, and BREAK. If an error is found the compiler will abort and you will need to go into your script to correct the error. COMMAND FORMAT ══════════════ All commands will be listed in the form: Command Name -> Command Syntax. <description of command here> The following conventions will be used in all command syntax in this document: COMMAND - All commands will be in capitals and must be typed in the format shown (see the note below.) <label> - A single word, no quotes or spaces. <variable#> - Any variable name (only). <number#> - Any numeric value (only). <string#> - A string value ("aBc 123") or any variable name. <value#> - A numeric value or any variable name that is used to store numeric values. <pathfile#> - A legal DOS filename including path information. If the path is excluded it will default to the BBS' main directory. A variable that stores the correct path/filename info may also be used. <filename#> - A legal DOS filename excluding path information. Commands that use this have the path info set automatically. A variable that has the filename stored in it may also be used. <prompt> - Either a text string or a variable name. Most of these are optional, so use them only if you want them. <relation> - Any of the following, but see the specific com- mand for verification: = Equal to <> Not equal to > Greater than >= Greater than or equal to < Less than <= Less than or equal to <option> - The value of this item is command-specific. <token#> - Any single item; see section 1.2 for a complete definition of a token. Note: If the command name is followed by a '<---' then the syntax for the command is just the command name. VBBS 6.12 Documentation -- 10-3 SPECIAL VARIABLES/CONSTANTS ═══════════════════════════ The script language contains the following restricted variables, which are read-only: $AGE - Age of user. $ANSI - Stores the user's current graphics setting. Set to OFF if using ASCII, ON if using ANSI, and ENH if using PDM's. $AVAILABLE - Stores the sysop availability flag. Y if sysop is available, N if not. $BAUD - Stores the user's connect speed. Returns "" if logged into node 0 (or other local node) and returns "CONSOLE" if logged in locally from the WFC screen. $BBSNAME - Stores the BBS' name, as shown in VCONFIG. $BELL - Stores ASCII code 7, causes a beep when printed. $BIRTHDATE - User birthdate in same format as $DATE. $BS - Stores ASCII code 8, causes the cursor to back up 1 space on current line when printed. It is not a destructive backspace. $CLEAR - Stores <CTRL>-<L> for ASCII users, stores the ANSI clear screen code for others when printed. $<color> - These nine variables are reserved as color codes: $RED, $BLUE, $CYAN, $GREEN, $YELLOW, $MAGENTA, $WHITE, $BLACK, and $NORM. See section 3.3 for more information. $CR - Stores ASCII code 13, causes a carriage return when printed (moves to column 1, current line.) $CREDITS - Number of credits user has. $CRLF - Causes both a $CR & $LF when printed (moves to column 1 of the next line.) $DATE - Stores the current system date as MM-DD-YYYY. $EXTRAx - The users extra variables values are stored in $EXTRA1 thru $EXTRA8. They can be changed with the SETEXTRA command. See section 8.2 for info. $FLAGS - This contains the list of all active general flags of the current user. Use the INSTR command with $FLAG and you will know if a particular flag is on if the result is non-zero. You can change the value of a flag with the SETFLAG command. See section 8.2 for info. $HANDLE - User's handle. $LF - Stores ASCII code 10, causes a linefeed when it's printed (same column position, next line.) $MAXTIME - Maximum minutes per day. $NAME - User's real name. $NODE - Stores your VirtualNET node # as set in VCONFIG. Default is 0 if you are not in VirtualNET. $PAGE - Number of lines to print before pause. $PORT - Returns present channel # of user (not COM port!) $SECURITY - User's security level, 250 and up is considered Co-sysop/Sysop access. Use TESTVAL and this variable to implement your own security. VBBS 6.12 Documentation -- 10-4 $SYSOP - Stores the sysop's name as set in VCONFIG. $TEXTPATH - Stores the path to your TXT directory. $TIME - Stores the current system time. $TIMELEFT - Number of minutes left for this session. $TIMEON - Number of minutes on for this session. $TIMESON - Total number of logons for the user. $TOTALMIN - Total number of minutes on since first logon. $USER - User's account number. $VIDEOMODE - This stores values similar to $ANSI, only they are #'s instead of words. Set to 0 if using ASCII, 1 if using ANSI, 2 if using PDM's, and 3 if using VGIX. INTERFACING WITH VBBS ═════════════════════ There are only two ways that you can run a script. You can either run the script from a function block or LINK to it from another script. The former is covered here and the latter is covered in section 7.3 - Passing Control. Go into the function block you wish to have run the script and add the following line on any but the first two lines in the .FB file: Z 001 2 Scripter | | | ^------This is the script name, NO extension. | | ^----------This is the command type that tells VBBS it is | | running a script. See section 7.3 | ^-------------This is the SL to be able to use the key (and | run the script.) ^----------------This is the key to press at the menu to load and run the script. PREPACKAGED SCRIPTS ═══════════════════ --> IMPORTANT NOTE: This section is best read after reading through the entire file but is included here to maintain the structure of this document. Do not let the unknown terms interfere with your reading, as they will all be explained elsewhere. There are many script authors out in the BBSing community that have written all sorts of scripted programs to perform prac- tically everything you could ever want. The most difficult part of using a script is knowing how to install it. What you should do first is pull up the script and look for comments that explain the script. Some will contain complete sets of instructions, while others will contain no comments at all. If the script con- tains few or no comments, then what you will need to do is: VBBS 6.12 Documentation -- 10-5 1> Make sure that all EXIT and LINK statements point to FB's or scripts that you actually have. If all else fails you can set all of these statements to EXIT to your main FB file. 2> Look for any statements that use file commands. Be sure to change these to valid paths on your system. 3> See if the script has any RET lines. If it does, try to find the CALL statements to the labels that appear a few lines before the RET. After you have done these steps you will then have the info you need to determine how the script should be used. If the script has no EXIT or LINK statements, or the script has a RET line with no CALL statement, then you must make the script part of an exis- ting one. The easiest way to do this is to just block-copy the entire script in before your final EXIT or LINK statement in your script if it has no unmatched RET statements. If there is an unmatched RET statement, then installing the new script is even easier. Somewhere in your script you need to add a CALL <label> statement with <label> being the label at the start of the new script. Then just add as the last line of your script the line '& <script name>'. You should be able to compile and run it at this point. Just remember, 'Nothing is Guaranteed!', so if you have a problem with a script and you can't get it to work try to either pick the code apart (if you can) or hop onto any VirtualNet BBS that carries a script dis- cussion sub and ask a few questions (or a few hundred, as needed). One of the script gurus may be able to help you out, and you might even be able to get in touch with the author.